Skip to content

Add browser Tracks events across admin screens and the editor - #179

Merged
smithjw1 merged 14 commits into
mainfrom
add/tracks-instrumentation
Nov 16, 2026
Merged

smithjw1 merged 14 commits into
mainfrom
add/tracks-instrumentation

Conversation

@smithjw1

@smithjw1 smithjw1 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Intent

Adds browser-side Tracks events across the admin screens and the block editor, so we can measure how sequences are built and how the dashboard and editor workflow tools are used. Until now, only server-side events reached Tracks. Events are recorded only where the VIP Telemetry library is loaded, and never on local. Event properties are counts, booleans, enums or IDs, never text a person typed.

What was done

Browser Tracks helper (src/common/tracks.js)

  • recordTracksEvent( event, properties ) adds the vip_workflows_ prefix and merges in the base properties PHP provides.
  • Tracker::get_client_properties() returns the VIP Telemetry library's core properties plus plugin_version. It's passed to the page as tracks on vipWorkflowsAdmin and vipWorkflowsEditor, and is null where the library isn't loaded. In that case, and on local, the helper records nothing.
  • Events go on the standard Tracks queue, window._tkq. The helper loads stats.wp.com/w.js itself on the first event, unless another plugin already has, so no screen loads it when nothing will be recorded. This is the same approach wp-parsely uses.
  • It deliberately doesn't use @automattic/calypso-analytics. That package's recordTracksEvent() silently drops events whose source isn't on its built-in allowlist, and vip isn't on it. Its consent check reads WordPress.com cookies that customer domains don't have. And it would add a 36 KB chunk.
  • The branch adds no dependencies.
  • A failed script load is retried on the next event. Errors are always caught, so telemetry can't break the screen.

Sequences

  • sequence_create_started and sequence_imported, on the Sequences list.
  • In the sequence editor:
    • sequence_stage_added, from all four ways of adding a stage;
    • sequence_post_status_added, sequence_assignment_added, sequence_tool_added, sequence_metadata_field_added;
    • sequence_stage_agent_selected, when an agent is chosen, not when it's cleared;
    • sequence_ai_publish_toggled.

My Work dashboard

  • dashboard_grouping_changed and dashboard_filter_changed. Both are recorded only after the view is saved, so a failed browser-storage write records nothing.
  • filter-change.js counts a filter only once it has a value. Filter values are never sent.

Settings

  • settings_experiment_toggled is recorded server-side, in the experiments REST endpoint, because the Settings screen reloads as soon as the save finishes, which would drop a browser event.
  • It compares the experiment's effective state before and after the save. So an experiment forced on or off by the vip_workflows_experiments filter records no change, and enabled is the state the experiment ends up in.

Block editor

  • editor_panel_toggled, when the Workflow panel is opened or closed. The open state a post loads with isn't counted.
  • editor_workflow_selected and editor_workflow_removed, both only once the request succeeds.
  • editor_transition_clicked, with where it was clicked.
  • editor_history_opened.

How to test

  1. npm run build (root) compiles clean.
  2. cd vip-workflows && composer test: unit tests pass, including TrackerTest and ExperimentsControllerTest.
  3. npm run test:unit:js: passes, including tracks.test.js, filter-change.test.js, panel-toggle-tracking.test.js and the My Work persistence tests.
  4. Off VIP (the PR preview or plain wp-env): open Sequences, My Work and a post in the editor. window.vipWorkflowsAdmin.tracks (or vipWorkflowsEditor.tracks) is null, and the Network tab shows no request to stats.wp.com or pixel.wp.com.
  5. As on VIP (wp-env): add an mu-plugin that defines Automattic\VIP\Telemetry\Telemetry and Automattic\VIP\Telemetry\Tracks\get_tracks_core_properties(), returning vip_env => 'production'. Then filter the Network tab to t.gif:
    • Click New sequence to get vip_workflows_sequence_create_started. Add a stage in the sequence editor to get vip_workflows_sequence_stage_added.
    • On My Work, change the grouping to get vip_workflows_dashboard_grouping_changed.
    • In the editor, open and close the Workflow panel, and click Show history.
    • With vip_env => 'local', nothing is requested.

🤖 Generated with Claude Code

Open WordPress Playground Preview

@smithjw1
smithjw1 force-pushed the add/tracks-instrumentation branch from a75d004 to a8342d3 Compare November 11, 2026 06:53
@smithjw1
smithjw1 marked this pull request as ready for review November 12, 2026 01:35
smithjw1 and others added 13 commits November 13, 2026 16:12
Adds src/common/tracks.js, the browser counterpart of the PHP Tracker:
same vip_workflows_ prefix and the same base properties, which PHP now
hands to the admin and editor bundles as `tracks`. Nothing is recorded
where the VIP Telemetry library isn't loaded or on local environments,
and the Tracks client is imported on the first event so screens that
record nothing never load stats.wp.com/w.js.

First event: vip_workflows_editor_history_opened, on Show history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adding a stage (with how: canvas menu, stage list, dropping a connection
or reconnecting an edge onto empty canvas), a post status, an
assignment, a required tool or a metadata field; choosing a stage's
agent; and toggling whether AI stages may publish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Filters are recorded when the applied set changes, with the field and
how many filters now apply; never their values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recorded by the experiments endpoint, once per experiment whose state
changes, rather than in the browser: the Settings screen reloads as soon
as its save resolves, which would drop an event still queued there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Workflow panel opening or closing (the plugin sidebar it replaced is
gone), a workflow being assigned from the Summary row or the required
modal, a transition being started from the panel or the header, and a
post being removed from its workflow. Assignments and removals are
recorded once they succeed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Tracks client's recordTracksEvent() drops every event whose source
is not on its own hard-coded list, which vip is not, so no
vip_workflows_ browser event ever reached Tracks. Queue events with
pushEventToTracksQueue() instead, after the same analytics consent check
recordTracksEvent() makes, and drop undefined values as it does.

Also forget a failed import of the client, so a transient chunk failure
no longer stops every later event on the page.

A new test runs the real client, unmocked, and checks the event reaches
the Tracks queue.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Record dashboard_grouping_changed after the view is saved, so a failed
localStorage write records nothing. Compare an experiment's effective state
before and after a toggle, so one pinned by the vip_workflows_experiments
filter records no change that never happened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The package dropped vip_workflows_ events unless its own recordTracksEvent()
was bypassed, and its consent check reads WordPress.com cookies that customer
domains never have. The helper now pushes onto window._tkq and loads
stats.wp.com/w.js itself on the first event, as wp-parsely does, unless the
script is already on the page. This removes the dependency and its 36 KB chunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Outbound calls now lists what this branch records: experiment toggles
from the server, and sequence editing, My Work filters and grouping, and
editor workflow actions from the browser. It says the browser loads
stats.wp.com/w.js on the first event, and sends nothing off VIP or in a
local environment. The data column now admits IDs and option values,
which the browser events carry; still no content.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ll has

mu-plugins removed get_tracks_core_properties(), which only merged
get_base_properties_of_track_event() and get_base_properties_of_track_user().
Merge those two directly. Without this the browser got no base properties
on any current VIP environment and recorded nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
get_client_properties() runs while an admin screen renders. Wrap the two
library helper calls in try/catch, returning null as when the library
isn't loaded, the same way record() handles the library. Name the
properties the helpers actually return in the docblock, and drop Pendo
from SPEC.md's outbound-calls row: mu-plugins no longer sends to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@smithjw1
smithjw1 force-pushed the add/tracks-instrumentation branch from 68c2200 to e7e8017 Compare November 14, 2026 00:19
@alecgeatches

Copy link
Copy Markdown

One question, although not a blocker, maybe a follow-up.

Should the browser events skip FedRAMP sites? The gate in tracks.js only skips when there are no base properties or vip_env is local, which matches how the VIP Telemetry library behaves for our server events, so this PR is consistent with what we already do. The browser path is a bit different though: it loads stats.wp.com/w.js into wp-admin and the editor's browser talks to Automattic directly, where the server events only ever showed the server. mu-plugins' Admin_Page_View_Tracker::is_enabled_for_environment() skips FedRAMP (VIP_IS_FEDRAMP) for its page views, so there may be a reason to do the same here. If this will run on FedRAMP sites, the same question probably applies to the server events already on main (tool_run_finished, agent_run_finished, transition_gate_finished, hourly_limit_reached).

alecgeatches
alecgeatches previously approved these changes Nov 16, 2026

@alecgeatches alecgeatches left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Provisionally approving, although see the comment above for a FedRAMP question about the new events. It looks like you've addressed all of Chris' concerns.

@smithjw1

Copy link
Copy Markdown
Contributor Author

One question, although not a blocker, maybe a follow-up.

Should the browser events skip FedRAMP sites? The gate in tracks.js only skips when there are no base properties or vip_env is local, which matches how the VIP Telemetry library behaves for our server events, so this PR is consistent with what we already do. The browser path is a bit different though: it loads stats.wp.com/w.js into wp-admin and the editor's browser talks to Automattic directly, where the server events only ever showed the server. mu-plugins' Admin_Page_View_Tracker::is_enabled_for_environment() skips FedRAMP (VIP_IS_FEDRAMP) for its page views, so there may be a reason to do the same here. If this will run on FedRAMP sites, the same question probably applies to the server events already on main (tool_run_finished, agent_run_finished, transition_gate_finished, hourly_limit_reached).

It's a good question. Because the events are going to our services, we don't have to exempt FedRAMP like we did with an external provider.

get_client_properties() held the two library helpers' names in
variables and called them through those. It's safe as written, but a
variable function call is easy to turn into something unsafe as the
code changes. The helpers are now imported with `use function` and
called by name, with the same function_exists() guards in front.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@smithjw1
smithjw1 merged commit 272e765 into main Nov 16, 2026
17 checks passed
@smithjw1
smithjw1 deleted the add/tracks-instrumentation branch November 16, 2026 18:13
@smithjw1 smithjw1 mentioned this pull request Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants